home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / a / asm_one / asm-onev1.25a.dms / in.adf / Release3.1 / AutoDocs3.1.lha / doc / nonvolatile.doc next >
Encoding:
Text File  |  1993-08-12  |  12.2 KB  |  353 lines
  1. TABLE OF CONTENTS
  2.  
  3. nonvolatile.library/--background--
  4. nonvolatile.library/DeleteNV
  5. nonvolatile.library/FreeNVData
  6. nonvolatile.library/GetCopyNV
  7. nonvolatile.library/GetNVInfo
  8. nonvolatile.library/GetNVList
  9. nonvolatile.library/SetNVProtection
  10. nonvolatile.library/StoreNV
  11. nonvolatile.library/--background--         nonvolatile.library/--background--
  12.  
  13.    PURPOSE
  14.     The nonvolatile library provides a simple means for an application
  15.     developer to manage nonvolatile storage.
  16.  
  17.    OVERVIEW
  18.     The nonvolatile library is meant to be used transparently across all
  19.     configurations. Currently, nonvolatile storage may consist of NVRAM
  20.     and/or disk devices. nonvolatile.library will automatically
  21.     access the best nonvolatile storage available in the system. Disk
  22.     based storage will be selected first and if not available, NVRAM
  23.     storage will be accessed.
  24.  
  25.     * NVRAM
  26.  
  27.     On low-end diskless Amiga platforms, NVRAM may be available. This
  28.     RAM will maintain its data contents when the system is powered down.
  29.     This is regardless of whether batteries or battery-backed clock are
  30.     present. The data stored in NVRAM is accessible only through the
  31.     ROM-based nonvolatile library funtion calls. The size of NVRAM
  32.     storage    is dependant on the system platform and is attainable through
  33.     the GetNVInfo() function.
  34.  
  35.     * Disk
  36.  
  37.     In keeping with the general configurability of the Amiga, the actual
  38.     disk location used by nonvolatile library when storing to disk may be
  39.     changed by the user.
  40.  
  41.     The prefs directory is used on the Amiga for storing many user
  42.     configurable options. The location for nonvolatile disk storage
  43.     is contained in the file prefs/env-archive/sys/nv_location. This
  44.     file should contain a data string that specifies a lockable location.
  45.     If the string does not specify a lockable location, the file will
  46.     be ignored.
  47.  
  48.     When opened, the nonvolatile library will search all drives within
  49.     the system until it finds this file and successfully accomplishes
  50.     a Lock on the location specified in the file. To force a rescan of
  51.     all drives, the library may be closed and reopened or execute the
  52.     GetNVInfo() function.
  53.  
  54.     A simple method for creating a floppy disk for saving nonvolatile
  55.     data is the following:
  56.  
  57.     Format a disk with the volume name NV
  58.     Create a file prefs/env-archive/sys/nv_location on this disk with
  59.       the following contents:  NV:nonvolatile
  60.     Create a directory nonvolatile
  61.  
  62.     The following is a script file that can be used to make a floppy
  63.     for use with nonvolatile library:
  64.  
  65.     .KEY Drive/A DiskName
  66.     .BRA {
  67.     .KET }
  68.     format Drive {Drive} Name {DiskName$NV} noicons
  69.     md {Drive}prefs
  70.     md {Drive}nonvolatile
  71.     md {Drive}prefs/env-archive
  72.     md {Drive}prefs/env-archive/sys
  73.     echo {DiskName$NV}:nonvolatile > {Drive}prefs/env-archive/sys
  74.      /nv_location
  75.  
  76. nonvolatile.library/DeleteNV                     nonvolatile.library/DeleteNV
  77.  
  78.    NAME
  79.     DeleteNV -- remove an entry from nonvoltatile storage. (V40)
  80.  
  81.    SYNOPSIS
  82.     success = DeleteNV(appName, itemName, killRequesters);
  83.     D0           A0        A1          D1
  84.  
  85.     BOOL DeleteNV(STRPTR, STRPTR, BOOL);
  86.  
  87.    FUNCTION
  88.     Searches the nonvolatile storage for the indicated entry and removes
  89.     it.
  90.  
  91.     The strings appName and itemName may not contain the '/' or ':'
  92.     characters. It is recommended that these characters be blocked
  93.     from user input when requesting AppName and ItemName strings.
  94.  
  95.    INPUTS
  96.     appName - NULL terminated string identifing the application that
  97.           created the data. Maximum length is 31.
  98.     ItemName - NULL terminated string uniquely identifing the data
  99.            within the application. Maximum length is 31.
  100.     killRequesters - suppress system requesters flag. TRUE if all system
  101.              requesters are to be suppressed during this function.
  102.              FALSE if system requesters are allowed.
  103.  
  104.    RESULT
  105.     success - TRUE will be returned if the entry is found and deleted.
  106.           If the entry is not found, FALSE will be returned.
  107.  
  108. nonvolatile.library/FreeNVData                 nonvolatile.library/FreeNVData
  109.  
  110.    NAME
  111.     FreeNVData -- release the memory allocated by a function of this
  112.               library. (V40)
  113.  
  114.    SYNOPSIS
  115.     FreeNVData(data);
  116.            A0
  117.  
  118.     VOID FreeNVData(APTR);
  119.  
  120.    FUNCTION
  121.     Frees a block of memory that was allocated by any of the following:
  122.     GetCopyNV(), GetNVInfo(), GetNVList().
  123.  
  124.    INPUTS
  125.     data - pointer to the memory block to be freed. If passed NULL,
  126.            this function does nothing.
  127.  
  128.    SEE ALSO
  129.     GetCopyNV(), GetNVInfo(), GetNVList()
  130.  
  131. nonvolatile.library/GetCopyNV                   nonvolatile.library/GetCopyNV
  132.  
  133.    NAME
  134.     GetCopyNV -- return a copy of an item stored in nonvolatile storage.
  135.              (V40)
  136.  
  137.    SYNOPSIS
  138.     data = GetCopyNV(appName, itemName, killRequesters);
  139.     D0         A0      A1        D1
  140.  
  141.     APTR GetCopyNV(STRPTR, STRPTR, BOOL);
  142.  
  143.    FUNCTION
  144.     Searches the nonvolatile storage for the indicated appName and
  145.     itemName. A pointer to a copy of this data will be returned.
  146.  
  147.     The strings appName and itemName may not contain the '/' or ':'
  148.     characters. It is recommended that these characters be blocked
  149.     from user input when requesting appName and itemName strings.
  150.  
  151.    INPUTS
  152.     appName - NULL terminated string indicating the application name
  153.           to be found. Maximum length is 31.
  154.     itemName - NULL terminated string indicated the item within the
  155.            application to be found. Maximum length is 31.
  156.     killRequesters - Suppress system requesters flag. TRUE if all system
  157.              requesters are to be suppressed during this function.
  158.              FALSE if system requesters are allowed.
  159.  
  160.    RESULT
  161.     data - pointer to a copy of the data found in the nonvolatile storage
  162.            assocated with appName and itemName. NULL will be returned
  163.            if there is insufficient memory or the appName/itemName does
  164.            not exist.
  165.  
  166.    SEE ALSO
  167.     FreeNVData(), <libraries/nonvolatile.h>
  168.  
  169. nonvolatile.library/GetNVInfo                   nonvolatile.library/GetNVInfo
  170.  
  171.    NAME
  172.     GetNVInfo -- report information on the current nonvolatile storage.
  173.              (V40)
  174.  
  175.    SYNOPSIS
  176.     information = GetNVInfo(killRequesters);
  177.     D0            D1
  178.  
  179.     struct NVInfo *GetNVInfo(BOOL);
  180.  
  181.    FUNCTION
  182.     Finds the user's preferred nonvolatile device and reports information
  183.     about it.
  184.  
  185.    INPUTS
  186.     killRequesters - suppress system requesters flag. TRUE if all system
  187.              requesters are to be suppressed during this function.
  188.              FALSE if system requesters are allowed.
  189.  
  190.    RESULT
  191.     information - pointer to an NVInfo structure. This structure contains
  192.               information on the NV storage media with the largest
  193.               storage. The structure contains 2 longword fields:
  194.               nvi_MaxStorage and nvi_FreeStorage. Both values are
  195.               rounded down to the nearest ten. The nvi_MaxStorage
  196.               field is defined as the total amount of nonvolatile
  197.               storage available on this device. The nvi_FreeStorage is
  198.               defined as the amount of available space for NVDISK or
  199.               the amount of non-locked storage for NVRAM. For NVDISK,
  200.               the nvi_FreeStorage takes into account the amount of
  201.               overhead room required to store a new App/Item. This
  202.               amount is 3 blocks to allow room for storing a new Item
  203.               file and possibly a new App directory. For NVRAM, the
  204.               amount of overhead is 5 bytes. However, the amount of
  205.               room required to store a new NVRAM item depends on the
  206.               length of the App and Item names. Refer to StoreNV()
  207.               function for storage details.
  208.  
  209.               This function may return NULL in the case of failure.
  210.  
  211.    SEE ALSO
  212.     FreeNVData(), StoreNV(), <libraries/nonvolatile.h>
  213.  
  214. nonvolatile.library/GetNVList                   nonvolatile.library/GetNVList
  215.  
  216.    NAME
  217.     GetNVList -- return a list of the items stored in nonvolatile
  218.              storage. (V40)
  219.  
  220.    SYNOPSIS
  221.     list = GetNVList(appName, killRequesters);
  222.     D0         A0      D1
  223.  
  224.     struct MinList *GetNVList(STRPTR, BOOL);
  225.  
  226.    FUNCTION
  227.     Returns a pointer to an Exec list of nonvolatile Items associated
  228.     with the appName requested.
  229.  
  230.     The string appName may not contain the '/' or ':' characters.
  231.     It is recommended that these characters be blocked from user input
  232.     when requesting an appName string.
  233.  
  234.    INPUTS
  235.     appName - NULL terminated string indicating the application name
  236.           to be matched. Maximum length is 31.
  237.     killRequesters - Suppress system requesters flag. TRUE if all system
  238.              requesters are to be suppressed during this function.
  239.              FALSE if system requesters are allowed.
  240.  
  241.    RESULT
  242.     list - a pointer to an Exec MinList of NVEntries. A NULL will be
  243.            returned if there is insufficient memory. If there are no
  244.            entries in the nonvolatile storage for the AppName, an
  245.            empty list will be returned.
  246.  
  247.    NOTE
  248.     The protection field contains more bits than are required for
  249.     storing the delete protection status. These bits are reserved
  250.     for other system usage and may not be zero. When checking for
  251.     the delete status use either the field mask NVIF_DELETE, or the
  252.     bit definition NVIB_DELETE.
  253.  
  254.    SEE ALSO
  255.     FreeNVData(), SetNVProtection()
  256.  
  257. nonvolatile.library/SetNVProtection       nonvolatile.library/SetNVProtection
  258.  
  259.    NAME
  260.     SetNVProtection -- set the protection flags. (V40)
  261.  
  262.    SYNOPSIS
  263.     success = SetNVProtection(appName, itemName, mask, killRequesters);
  264.     D0              A0       A1         D2    D1
  265.  
  266.     BOOL SetNVProtection(STRPTR, STRPTR, LONG, BOOL);
  267.  
  268.    FUNCTION
  269.     Sets the protection attributes for an item currently in the
  270.     nonvolatile storage.
  271.  
  272.     Although 'mask' is LONG only the delete bit, NVEF_DELETE/NVEB_DELETE,
  273.     may be set. If any other bits are set this function will return
  274.     FALSE.
  275.  
  276.     The strings appName and itemName may not contain the '/' or ':'
  277.     characters. It is recommended that these characters be blocked
  278.     from user input when requesting AppName and ItemName strings.
  279.  
  280.    INPUTS
  281.     appName - NULL terminated string indicating the application name
  282.           to be matched. Maximum length is 31.
  283.     itemName - NULL terminated string indicated the item within the
  284.            application to be found. Maximum length is 31.
  285.     mask - the new protection mask. Only set the delete bit otherwise
  286.            this function WILL CRASH.
  287.     killRequesters - suppress system requesters flag. TRUE if all system
  288.              requesters are to be suppressed during this function.
  289.              FALSE if system requesters are allowed.
  290.  
  291.    RESULT
  292.     success - FALSE if the protection could not be change (ie the data
  293.           does not exist).
  294.  
  295.    SEE ALSO
  296.     GetNVList(), <libraries/nonvolatile.h>
  297.  
  298. nonvolatile.library/StoreNV                       nonvolatile.library/StoreNV
  299.  
  300.    NAME
  301.     StoreNV -- store data in nonvolatile storage. (V40)
  302.  
  303.    SYNOPSIS
  304.     error = StoreNV(appName, itemName, data, length, killRequesters);
  305.     D0        A0     A1       A2    D0     D1
  306.  
  307.     UWORD StoreNV(STRPTR, STRPTR, APTR, ULONG, BOOL);
  308.  
  309.    FUNCTION
  310.     Saves some data in nonvolatile storage. The data is tagged with
  311.     AppName and ItemName so it can be retrieved later. No single
  312.     item should be larger than one fourth of the maximum storage as
  313.     returned by GetNVInfo().
  314.  
  315.     There is no data compression associated with this function.
  316.  
  317.     The strings, AppName and ItemName, should be short, but descriptive.
  318.     They need to be short since the string is stored with the data and
  319.     the nonvolatile storage for a stand alone game system is limited.
  320.     The game system allows the user to selectively remove entries from
  321.     storage, so the string should be desriptive.
  322.  
  323.     The strings AppName and ItemName may not contain the '/' or ':'
  324.     characters. It is recommended that these characters be blocked
  325.     from user input when requesting AppName and ItemName strings.
  326.  
  327.    INPUTS
  328.     appName - NULL terminated string identifying the application
  329.           creating the data. Maximum length is 31.
  330.     itemName - NULL terminated string uniquely identifying the data
  331.            within the application. Maximum length is 31.
  332.     data - pointer to the memory block to be stored.
  333.     length - number of bytes to be stored in the units of tens of
  334.          bytes. For example, if you have 23 bytes to store length = 3;
  335.          147 byte then length = 15.
  336.     killRequesters - suppress system requesters flag. TRUE if all system
  337.              requesters are to be suppressed during this function.
  338.              FALSE if system requesters are allowed.
  339.  
  340.    RESULT
  341.     error - 0                means no error,
  342.             NVERR_BADNAME    error in AppName, or ItemName.
  343.             NVERR_WRITEPROT  Nonvolatile storage is read only.
  344.             NVERR_FAIL       Failure in writing data (nonvolatile storage
  345.                  full, or write protected).
  346.             NVERR_FATAL      Fatal error when accessing nonvolatile
  347.                  storage, possible loss of previously saved
  348.                  nonvolatile data.
  349.  
  350.    SEE ALSO
  351.     GetCopyNV(), GetNVInfo()
  352.  
  353.